\defmodule {Accumulate}

A subclass of \externalclass{umontreal.iro.lecuyer.stat}{StatProbe},
for collecting statistics on a
variable that evolves in simulation time, with a piecewise-constant trajectory.
Each time the variable changes its value, the method \method{update}{double}
must be called to inform the probe of the new value.
The probe can be reinitialized by \method{init}{}.

\bigskip\hrule

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{code}\begin{hide}
/*
 * Class:        Accumulate
 * Description:  collects statistics on a variable that evolves in
                 simulation time
 * Environment:  Java
 * Software:     SSJ
 * Copyright (C) 2001  Pierre L'Ecuyer and Universite de Montreal
 * Organization: DIRO, Universite de Montreal
 * @author
 * @since

 * SSJ is free software: you can redistribute it and/or modify it under
 * the terms of the GNU General Public License (GPL) as published by the
 * Free Software Foundation, either version 3 of the License, or
 * any later version.

 * SSJ is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.

 * A copy of the GNU General Public License is available at
   <a href="http://www.gnu.org/licenses">GPL licence site</a>.
 */
\end{hide}
package umontreal.iro.lecuyer.simevents;\begin{hide}
// This class doesn't belong to package stat because objects of this class
// always depend of Simulator

import java.util.Observable;
import umontreal.iro.lecuyer.util.PrintfFormat;
import umontreal.iro.lecuyer.stat.StatProbe;
\end{hide}

public class Accumulate extends StatProbe implements Cloneable \begin{hide} {

   private double initTime;    // Initialization time.
   private double lastTime;    // Last update time.
   private double lastValue;   // Value since last update.
   private Simulator sim;
\end{hide}
\end{code}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection* {Constructors}
\begin{code}

   public Accumulate() \begin{hide} {
      super();
      sim = Simulator.getDefaultSimulator();
      init();
   } \end{hide}
\end{code}
  \begin{tabb}  Constructs a new \texttt{Accumulate} statistical probe using the
  default simulator and initializes it by invoking \texttt{init()}.
 \end{tabb}
\begin{code}

   public Accumulate (Simulator inSim) \begin{hide} {
      super();
      if (inSim == null)
          throw new NullPointerException();
      sim = inSim;
      init();
   } \end{hide}
\end{code}
  \begin{tabb}  Constructs a new \texttt{Accumulate} statistical probe linked to
    the given simulator,
   and initializes it by invoking \texttt{init()}.
 \end{tabb}
 \begin{htmlonly}
   \param{inSim}{the simulator of the current variable}
\end{htmlonly}
\begin{code}

   public Accumulate (String name) \begin{hide} {
      super();
      sim = Simulator.getDefaultSimulator();
      this.name = name;
      init();
   } \end{hide}
\end{code}
  \begin{tabb}  Constructs and initializes a new \texttt{Accumulate}
   statistical probe with name \texttt{name} and initial time 0, using the default simulator.
 \end{tabb}
\begin{code}

   public Accumulate (Simulator inSim, String name) \begin{hide} {
      super();
      if (inSim == null)
          throw new NullPointerException();
      sim = inSim;
      this.name = name;
      init();
   } \end{hide}
\end{code}
  \begin{tabb}  Constructs-initializes a new \texttt{Accumulate}
   statistical probe with name \texttt{name} and initial time 0.
 \end{tabb}
\begin{htmlonly}
   \param{name}{descriptive name for the probe}
   \param{inSim}{the simulator of the current variable}
\end{htmlonly}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection* {Methods}
\begin{code}

   public void init() \begin{hide} {
       maxValue = Double.MIN_VALUE;
       minValue = Double.MAX_VALUE;
       lastValue = 0.0;
       sumValue = 0.0;
       // May start the accumulator at t > 0; for ex., a warm-up period or
       // other reasons
       initTime = lastTime = sim.time();
   } \end{hide}
\end{code}
  \begin{tabb}  Initializes the statistical collector and puts the current
   value of the corresponding variable to 0.
   \textbf{Note:} the initialization time, the last update time and
   the simulation time are not reset to 0 by this method. For this,
   \texttt{Sim.init()} must be used.
 \end{tabb}
\begin{code}

   public void init (double x) \begin{hide} {
       init();  update (x);
   } \end{hide}
\end{code}
  \begin{tabb}  Same as \method{init}{} followed by \method{update}{double}\texttt{(x)}.
 \end{tabb}
\begin{htmlonly}
   \param{x}{initial value of the probe}
\end{htmlonly}
\begin{code}

   public void update()\begin{hide} {
      update (lastValue);
   }\end{hide}
\end{code}
\begin{tabb}  Updates the accumulator using the last value passed
  to \method{update}{double}.
\end{tabb}
\begin{code}

   public void update (double x) \begin{hide} {
      if (collect) {
         double time = sim.time();
         if (x < minValue) minValue = x;
         if (x > maxValue) maxValue = x;
         sumValue += lastValue * (time - lastTime);
         lastValue = x;
         lastTime = time;
      }
      if (broadcast) {
         //setChanged();
         notifyListeners (x);
      }
   }\end{hide}
\end{code}
  \begin{tabb}  Gives a new observation \texttt{x} to the statistical collector.
   If broadcasting to observers is activated for this object,
   this method will also transmit the new information to the
   registered observers by invoking the methods
%   \texttt{setChanged}
%   and \externalmethod{java.util}{Observable}{notifyListeners}{}~{\tt
%   (new Double (x))}
   \method{notifyListeners}{double}.
%    inherited from
%   \externalclass{java.util}{Observable}.
 \end{tabb}
\begin{htmlonly}
   \param{x}{new observation given to the probe}
\end{htmlonly}
\begin{hide}
\begin{code}

   public double sum() \begin{hide} {
      update (lastValue);
      return sumValue;
   } \end{hide}

   public double average() \begin{hide} {
      update (lastValue);
      double periode = lastTime - initTime;
      if (periode > 0.0)  return sumValue/periode;
      else  return 0.0;
   }\end{hide}
\end{code}
  \begin{tabb}  Returns the time-average since the last initialization
    to the last call to \texttt{update}.
 \end{tabb}
\begin{code}\begin{hide}
   public String shortReportHeader() {
      PrintfFormat pf = new PrintfFormat();
      pf.append (-9, "from time").append ("   ");
      pf.append (-9, "to time").append ("   ");
      pf.append (-8, "   min").append ("   ");
      pf.append (-8, "   max").append ("   ");
      pf.append (-10, " average");
      return pf.toString();
   }

   public String shortReport() {
      update();
      PrintfFormat pf = new PrintfFormat();
      pf.append (9, 2, 2, getInitTime()).append ("   ");
      pf.append (9, 2, 2, getLastTime()).append ("   ");
      pf.append (8, 3, 2, min()).append ("   ");
      pf.append (8, 3, 2, max()).append ("   ");
      pf.append (10, 3, 2, average());
      return pf.toString();
   }
\end{hide}
\end{code}
\begin{code}

   public String report() \begin{hide} {
      update (lastValue);
      PrintfFormat str = new PrintfFormat();
      str.append ("REPORT on Accumulate stat. collector ==> " + name);
      str.append (PrintfFormat.NEWLINE + "      from time   to time       min         max");
      str.append ("         average").append(PrintfFormat.NEWLINE);
      str.append (12, 2, 2, initTime);
      str.append (13, 2, 2, lastTime);
      str.append (11, 3, 2, minValue);
      str.append (12, 3, 2, (double)maxValue);
      str.append (14, 3, 2, (double)average()).append (PrintfFormat.NEWLINE);

      return str.toString();
    }\end{hide}
\end{code}
  \begin{tabb}  Returns a string containing a report on this collector since its
   last initialization.
 \end{tabb}
\end{hide}
\begin{code}

   public double getInitTime()\begin{hide} {
      return initTime;
   }\end{hide}
\end{code}
\begin{tabb}   Returns the initialization time for this object.
  This is the simulation time when \method{init}{} was called for
  the last time.
\end{tabb}
\begin{htmlonly}
   \return{the initialization time for this object}
\end{htmlonly}
\begin{code}

   public double getLastTime()\begin{hide} {
      return lastTime;
   }\end{hide}
\end{code}
\begin{tabb}   Returns the last update time for this object.
   This is the simulation time of the last call to \method{update}{} or
   the initialization time if \method{update}{} was never called after
   \method{init}{}.
\end{tabb}
\begin{htmlonly}
   \return{the last update time of this object}
\end{htmlonly}
\begin{code}

   public double getLastValue()\begin{hide} {
      return lastValue;
   }\end{hide}
\end{code}
\begin{tabb}  Returns the value passed to this probe by the last call
   to its \method{update}{} method (or the initial value if
   \method{update}{} was never called after \method{init}{}).
\end{tabb}
\begin{htmlonly}
   \return{the last update value for this object}
\end{htmlonly}
\begin{code}

   public Simulator simulator() \begin{hide} {
      return sim;
   } \end{hide}
\end{code}
 \begin{tabb}   Returns the simulator associated with this statistical probe.
 \end{tabb}
\begin{htmlonly}
   \return{the associated simulator.}
\end{htmlonly}
\begin{code}

   public void setSimulator(Simulator sim) \begin{hide} {
       if (sim == null)
          throw new NullPointerException();
      this.sim = sim;
   } \end{hide}
\end{code}
 \begin{tabb}   Sets the simulator associated with this probe to \texttt{sim}.
   One should call \method{init}{} after this method to reset the statistical probe.
 \end{tabb}
\begin{htmlonly}
   \param{sim}{the simulator of this probe}
\end{htmlonly}
\begin{code}

   public Accumulate clone()\begin{hide} {
      try {
         return (Accumulate)super.clone();
      } catch (CloneNotSupportedException e) {
         throw new IllegalStateException ("Accumulate can't clone");
      }
   }\end{hide}
\end{code}
\begin{tabb} Clone this object.
\end{tabb}
\begin{code}\begin{hide}
}\end{hide}
\end{code}
